<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>Implement debug sequences</title>
<title>CMSIS-Pack: Implement debug sequences</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="cmsis.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="printComponentTabs.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 46px;">
  <td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">CMSIS-Pack
   &#160;<span id="projectnumber">Version 1.6.3</span>
   </div>
   <div id="projectbrief">Delivery Mechanism for Software Packs</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<div id="CMSISnav" class="tabs1">
    <ul class="tablist">
      <script type="text/javascript">
		<!--
		writeComponentTabs.call(this);
		//-->
      </script>
	  </ul>
</div>
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Usage&#160;and&#160;Description</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('dbg_debug_sqns.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Implement debug sequences </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Most Cortex-M devices rely on Arm Debug Interface (ADI) that specifies standard interface for accessing debug functionality on the processor. However due to implementation-specific variations it can still be challenging for debug tool vendors to provide reliable debugging experience for complex devices. Device vendors can use <a class="el" href="debug_description.html#pdsc_SequenceNameEnum_pg">debug access sequences</a> to customize the debugger behavior for a particular device.</p>
<p>Section <a class="el" href="debug_description.html#usage_of_sequences">Usage of debug access sequences</a> provides working example flows that can be implemented in a debugger. By overwriting the <a class="el" href="debug_description.html#default_sequences">predefined debug sequences</a> it is possible to customize the debugger operation for a specific device. The syntax and available functions are described in details in <a class="el" href="debug_description.html#writing_sequences">Writing debug access sequences</a>. This chapter explains the common cases that can be covered using debug sequences:</p>
<ul>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_dbgconf">Enable device-specific debug configurations</a></li>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_errors">Ignore access errors</a></li>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_trace">Configure trace</a></li>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_reset">Implement reset for debug access</a></li>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_boot">Support bootloader operation</a></li>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_multicore">Handle debug in multi-core systems</a></li>
</ul>
<p>The examples provided are quite generic demonstrating the concept to follow when addressing a specific scenario. However actual implementation shall always take device specific behavior into account.</p>
<h1><a class="anchor" id="dbg_sqns_dbgconf"></a>
Enable device-specific debug configurations</h1>
<p>The debug configuration options available in the debug IDEs mostly cover quite generic scenarios applicable to a wide set of devices and architectures, for example whether to use reset for debug connection and what type of reset, whether to stop after debug connection or not and so on. <a class="el" href="dbg_setup_access.html">Configure debug access</a> describes how to use debug descriptions to specify the configuration options available for the device and how to pre-select the default values.</p>
<p>But often there is a need to provide developers with some debug configuration options that are very device-specific. This can vary from simple SWO pin and clock source selection for tracing to more complex bootloader configuration or secure debug provisioning and multi-core system debug.</p>
<p>The <a class="el" href="pdsc_family_pg.html#element_debugvars">debugvars</a> element allows to define custom global debug access variables. Their values can also be made configurable via a project-specific <a class="el" href="pdsc_family_pg.html#debugvars_configfile">debug configuration file</a> (<b>*.dbgconf</b>). It is recommended to implement this file with <a class="el" href="configWizard.html">Configuration Wizard annotations</a> to enable simple graphical configuration view. <a class="el" href="debug_description.html#default_sequences">Predefined debug access sequences</a> can be overwritten where needed and use the custom debug variables. If a user-defined global access variable is not specified in the *.dbgconf file, then the value provided in the variable definition in the pdsc file is applied.</p>
<p>Documentation for the <a class="el" href="pdsc_family_pg.html#element_debugvars">debugvars</a> provides an example for trace SWO pin selection via a *.dbgconf file. Below is also an example that uses a custom global debug variable <b>Dbg_CR</b> for specifying whether the program shall stop after bootloader execution or not:</p>
<p><b> Use of debugvars in a pdsc file: </b></p>
<div class="fragment"><div class="line">... </div>
<div class="line">  &lt;debugvars configfile=<span class="stringliteral">&quot;Debug/LPC84x.dbgconf&quot;</span>&gt;&gt;</div>
<div class="line">    __var Dbg_CR = 0x00000000;  <span class="comment">// DBG_CR, with default value 0x00000000</span></div>
<div class="line">  &lt;/debugvars&gt;</div>
<div class="line">  ...</div>
<div class="line">    <span class="comment">// ResetCatchSet Sequence LPC84x</span></div>
<div class="line">    &lt;sequence name=<span class="stringliteral">&quot;ResetCatchSet&quot;</span>&gt;</div>
<div class="line">      ... <span class="comment">// initial setup</span></div>
<div class="line">          </div>
<div class="line">      &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;Dbg_CR == 0x00000000&quot;</span> info=<span class="stringliteral">&quot;Stop after bootloader disabled&quot;</span>&gt;</div>
<div class="line">        &lt;block&gt;</div>
<div class="line">          value = Read32(DEMCR_Addr);</div>
<div class="line">          Write32(DEMCR_Addr, (value | 0x00000001));                     <span class="comment">// Enable Reset Vector Catch in DEMCR</span></div>
<div class="line">        &lt;/block&gt;</div>
<div class="line">      &lt;/control&gt;</div>
<div class="line"></div>
<div class="line">      &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;Dbg_CR == 0x00000001&quot;</span> info=<span class="stringliteral">&quot;Stop after bootloader enabled&quot;</span>&gt;</div>
<div class="line">        &lt;block&gt;</div>
<div class="line">          value = Read32(DEMCR_Addr);</div>
<div class="line">          Write32(DEMCR_Addr, (value &amp;amp; (~0x00000001)));              <span class="comment">// Disable Reset Vector Catch in DEMCR</span></div>
<div class="line">        &lt;/block&gt;</div>
<div class="line">      &lt;/control&gt;</div>
<div class="line">      ...</div>
<div class="line">    &lt;/sequence&gt;</div>
<div class="line">  ...</div>
</div><!-- fragment --><p><b>*.dbgconf file: source code</b> </p>
<div class="fragment"><div class="line"><span class="comment">// &lt;&lt;&lt; Use Configuration Wizard in Context Menu &gt;&gt;&gt;</span></div>
<div class="line"></div>
<div class="line"><span class="comment">// &lt;h&gt;Debug Configuration</span></div>
<div class="line"><span class="comment">//   &lt;o.0&gt;    StopAfterBootloader       &lt;i&gt; Stop after Bootloader</span></div>
<div class="line"><span class="comment">// &lt;/h&gt;</span></div>
<div class="line">Dbg_CR = 0x00000001;</div>
<div class="line"></div>
<div class="line"><span class="comment">// &lt;&lt;&lt; end of configuration section &gt;&gt;&gt;</span></div>
</div><!-- fragment --><p><b>*.dbgconf file: Configuration Wizard view</b></p>
<div class="image">
<img src="dbgconf_confWizard.png" alt="dbgconf_confWizard.png"/>
</div>
<p>In the same way custom debug variables can be used to provide configuration for device-specific debug registers that then can be programmed via debug sequences.</p>
<h1><a class="anchor" id="dbg_sqns_errors"></a>
Ignore access errors</h1>
<p>In some cases the debug access errors need to be ignored to support device-specific implemenation. For that the predefined debug access sequence can be overwritten by duplicating the original code with the error handling disabled in required places using predefined debug access variable <a class="el" href="debug_description.html#__errorcontrol">__errorcontrol</a>.</p>
<p>Below is an example for an NXP IMXRT1051 family:</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetSystem&quot;</span>&gt;</div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    <span class="comment">// System Control Space (SCS) offset as defined in Armv6-M/Armv7-M.</span></div>
<div class="line">    __var SCS_Addr   = 0xE000E000;</div>
<div class="line">    __var AIRCR_Addr = SCS_Addr + 0xD0C;</div>
<div class="line">    __var DHCSR_Addr = SCS_Addr + 0xDF0;</div>
<div class="line">    </div>
<div class="line">    __errorcontrol = 0x1;     <span class="comment">// Skip errors, write to AIRCR.SYSRESETREQ may not be able to finish with OK response</span></div>
<div class="line">    <span class="comment">// Execute SYSRESETREQ via AIRCR</span></div>
<div class="line">    Write32(AIRCR_Addr, 0x05FA0004);</div>
<div class="line">    __errorcontrol = 0x0;     <span class="comment">// Honor errors again</span></div>
<div class="line">    </div>
<div class="line">    DAP_Delay(20000);         <span class="comment">// Delay of 20ms to let reset finish. Otherwise access to DHCSR can fail with too fast debug units.</span></div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">  </div>
<div class="line">  <span class="comment">//Reset Recovery: Wait for DHCSR.S_RESET_ST bit to clear on read </span></div>
<div class="line">  &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;(Read32(DHCSR_Addr) &amp;amp; 0x02000000)&quot;</span> timeout=<span class="stringliteral">&quot;500000&quot;</span>/&gt;</div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><p>In this implementation the standard system reset via AIRCR temporarily disables the DAP resulting in an access error. That could cause a debugger to disconnect. To overcome this the error handling is disabled before register write (<em>__errorcontrol = 0x1;</em>) and then enabled after it again. Additionally a delay is introduced (<em>DAP_Delay(20000);</em>) to allow reset to complete. The rest of the code is same as in the default <a class="el" href="debug_description.html#resetSystem">ResetSystem</a> implementation.</p>
<h1><a class="anchor" id="dbg_sqns_trace"></a>
Configure trace</h1>
<p>A common case that requires use of debug access sequences is trace configuration. <a class="el" href="debug_description.html#default_sequences">Predefined debug access sequences</a> have two trace-related sequences: <a class="el" href="debug_description.html#TraceStart">TraceStart</a> and <a class="el" href="debug_description.html#TraceStop">TraceStop</a> that are being called when trace is enabled in the project. The <code>TraceStart</code> sequence is executed at the end of the initial debug connection to the target and after device reset while <code>TraceStop</code> is executed at the beginning of debug disconnect.</p>
<p>By default these sequences are empty and often need to be implemented in the .pdsc file to support device-specific behavior, for example to differentiate configuration for 1-pin SWO trace and 5-pin ETM trace (TPIU).</p>
<p>For example:</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;TraceStart&quot;</span>&gt;</div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    <span class="comment">// obtain project trace configuration from global variable __traceout</span></div>
<div class="line">    __var traceSWO  = (__traceout &amp;amp; 0x1) != 0;</div>
<div class="line">    __var traceTPIU = (__traceout &amp;amp; 0x2) != 0;</div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">  </div>
<div class="line">  &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;traceSWO&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      Sequence(<span class="stringliteral">&quot;EnableTraceSWO&quot;</span>);</div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/control&gt;</div>
<div class="line">  </div>
<div class="line">  &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;traceTPIU&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      Sequence(<span class="stringliteral">&quot;EnableTraceTPIU&quot;</span>);</div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/control&gt;</div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><p>Note that the code above uses following features allowed in debug access sequences:</p>
<ul>
<li>read access to a predefined global debug access variable <a class="el" href="debug_description.html#__traceout">__traceout</a>.</li>
<li>implements the pre-defined debug sequence <code>TraceStart</code> </li>
<li>calls custom debug sequences <code>EnableTraceSWO</code> ,<code>EnableTraceTPIU</code> </li>
</ul>
<p>Implementation of custom debug access sequences <code>traceEnableSWO</code> and <code>traceEnableTPIU</code> is a means to better structure the sequence implementations. Their content is highly vendor and device-specific. Common functionality of such sequences is to trace on the device, configure trace clock and assign trace pin(s). But the complexity of the code varies significantly depending on the device functionalities.</p>
<p>Below is a simple example of <code>EnableTraceSWO</code> for Microchip SAMS70 family, that also demonstrates the use of a user-defined global debug access variable (<code>TracePCK3</code>) configurable via a debug configuration file <code>SAMx7.dbgconf</code>. See <a class="el" href="dbg_debug_sqns.html#dbg_sqns_dbgconf">Enable device-specific debug configurations</a> for additional information about custom global debug variables and *.dbgconf file.</p>
<div class="fragment"><div class="line">...</div>
<div class="line">&lt;family Dfamily=<span class="stringliteral">&quot;SAMV70&quot;</span> Dvendor=<span class="stringliteral">&quot;Microchip:3&quot;</span>&gt;</div>
<div class="line">  &lt;debugvars configfile=<span class="stringliteral">&quot;samv70/keil/debug/SAMx7.dbgconf&quot;</span> version=<span class="stringliteral">&quot;1.0.0&quot;</span>&gt;</div>
<div class="line">    <span class="comment">// Debug Access Variables</span></div>
<div class="line">    __var TracePCK3 = 0x00000000;                <span class="comment">// Trace Clock Source Selection and Prescaler</span></div>
<div class="line">  &lt;/debugvars&gt;</div>
<div class="line">     </div>
<div class="line">  &lt;sequence name=<span class="stringliteral">&quot;EnableTraceSWO&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      Write32(0x400E06E4, 0x504D4300);           <span class="comment">// Disable PMC write protection</span></div>
<div class="line">      Write32(0x400E064C, TracePCK3);            <span class="comment">// Select clock source and prescaler for PCK3</span></div>
<div class="line">      Write32(0x400E0600, (1 &amp;lt;&amp;lt; 11));      <span class="comment">// Enable PCK3</span></div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/sequence&gt;</div>
<div class="line">  ...</div>
</div><!-- fragment --><p>Some devices can require that trace clock is enabled already at <a class="el" href="debug_description.html#DebugDeviceUnlock">DebugDeviceUnlock</a> sequence to ensure that access to global trace components is available when reading the ROM table and processor features. In such cases corresponding functionality needs to be moved from <b>TraceStart</b> to <b>DebugDeviceUnlock</b> sequence and check if trace is enabled via the <b>__traceout</b> variable.</p>
<h1><a class="anchor" id="dbg_sqns_reset"></a>
Implement reset for debug access</h1>
<p>This section explains reset debug sequences for systems with a single CPU. Multi-core specifics are covered in <a class="el" href="dbg_debug_sqns.html#dbg_sqns_multicore">Handle debug in multi-core systems</a>.</p>
<p>Reset is an important part of debug operation and is used to bring the device into a known state from which debug connection can be reliably established. Reset also allows users to debug their code from the very beginning. In the typical case when user initiates a debug session the debugger connects to the device, and resets the processor to ensure its fresh start, and then stops the CPU before user application is started.</p>
<p>Sometimes it is needed to connect to a running target ("hot debug") without any resets performed when establishing a debug connection. Since there is no resets this is out of scope for the current section.</p>
<p>The figure below shows an example reset flow in a debugger (copied from <a class="el" href="debug_description.html#usage_of_sequences">Usage of debug access sequences</a>):</p>
<div class="image">
<img src="Reset.png" alt="Reset.png"/>
</div>
<p><b>CPU halt and ResetCatchSet</b></p>
<p>In the flow shown above the debugger first decides whether to halt the processor after the reset or not. This decision depends on the project configuration but also on when and how the reset is requested (automatically by debugger during or after debug connect, or manually by user through IDE, etc.).</p>
<p>If processor halt after reset is needed then <a class="el" href="debug_description.html#resetCatchSet">ResetCatchSet</a> sequence is executed before performing the reset operation. Default implementation of <b>ResetCatchSet</b> enables and configures Cortex-M Reset Vector Catch functionality so that the core is stopped right after reset thus allowing users to debug the program from the very start. In some cases <b>ResetCatchSet</b> needs to be overwritten, for example for <a class="el" href="dbg_debug_sqns.html#dbg_sqns_boot">Support bootloader operation</a>.</p>
<p><b>Reset types</b></p>
<p>There are 3 predefined reset types and a custom reset type that debugger chooses from when performing a reset. The choice depends on the project configuration and <a class="el" href="pdsc_family_pg.html#defaultResetSequence">defaultResetSequence</a> value. Corresponding reset debug sequence is executed to perform required reset type.</p>
<p>The reset types are listed below with details described in the referenced documentation.</p>
<ul>
<li><a class="el" href="debug_description.html#resetHardware_Descr">ResetHardware</a> is a system-wide reset without debug domain executed via the dedicated debugger reset line, e.g. nRST.</li>
<li><a class="el" href="debug_description.html#resetSystem_Descr">ResetSystem</a> is a software-triggered system-wide reset that preserves established debug connection.</li>
<li><a class="el" href="debug_description.html#resetProcessor_Descr">ResetProcessor</a> is a software-triggered local reset for a processor only.</li>
<li><b>CustomResetName</b> sequence is used when a user-defined debug sequence is assigned to the <a class="el" href="pdsc_family_pg.html#defaultResetSequence">defaultResetSequence</a> attribute. This can be implemented when very special reset type is needed that cannot be performed by modifying predefined reset types.</li>
</ul>
<p><a class="anchor" id="dbg_sqns_reset_catchClear"></a><b>CPU halt and ResetCatchClear</b></p>
<p>After reset is performed and the processor is halted (on the breakpoint enabled in <b>ResetCatchSet</b>) the <a class="el" href="debug_description.html#resetCatchClear">ResetCatchClear</a> sequence is executed. The default implementation may need to be overwritten to support bootloader as explaine in <a class="el" href="dbg_debug_sqns.html#dbg_sqns_boot">Support bootloader operation</a>.</p>
<h1><a class="anchor" id="dbg_sqns_boot"></a>
Support bootloader operation</h1>
<p>Systems with built-in ROM bootloader often require special handling to ensure that debug is correctly started from the user application.</p>
<p>In particular the reset flow described in <a class="el" href="dbg_debug_sqns.html#dbg_sqns_reset">Implement reset for debug access</a> most likely needs special adjustments for bootloader operation. After device reset the bootloader gets executed first. The debugger needs to take that into account and stop the processor with a breakpoint just before the application is started. For some devices this is also essential because debug can be disabled during bootloader execution for asset protection purposes.</p>
<p>The default implementation of <a class="el" href="debug_description.html#resetCatchSet">ResetCatchSet</a> sequence halts the core right after reset. This however would be before the bootloader is started and hence may be not relevant for application development or even not possible to debug if bootloader code is not available.</p>
<p>To overcome this problem the <b>ResetCatchSet</b> sequence needs to be overwritten in the .pdsc file of the Device Family Pack (DFP). In constrast to the default implementation the Reset Vector Catch shall be disabled allowing uninterrupted bootloader execution after reset. To halt the core before the application starts the sequence additionally sets a breakpoint at the Reset Vector, where the execution jumps to after bootloader is finished.</p>
<p><a class="anchor" id="example1_resetCatchSet"></a><b>Example 1: ResetCatchSet</b></p>
<p>The code below gives an example for an Armv8-M system with the vector table placed at address 0x00000000:</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetCatchSet&quot;</span>&gt;</div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    __var DHCSR_Addr    = 0xE000EDF0;</div>
<div class="line">    __var DEMCR_Addr    = 0xE000EDFC;</div>
<div class="line">    __var FP_CTRL_Addr  = 0xE0002000;</div>
<div class="line">    __var FP_COMP0_Addr = 0xE0002008;</div>
<div class="line">    __var FPB_KEY       = 0x00000002;</div>
<div class="line">    __var FPB_ENABLE    = 0x00000001;</div>
<div class="line">    __var value         = 0;</div>
<div class="line">    __var resetVect     = 0x00000000;</div>
<div class="line">  </div>
<div class="line">    value = Read32(DEMCR_Addr);</div>
<div class="line">    Write32(DEMCR_Addr, (value &amp;amp; ~0x00000001));    <span class="comment">// Disable Reset Vector Catch</span></div>
<div class="line">   </div>
<div class="line">    resetVect = Read32(0x00000004);                     <span class="comment">// Read Reset Vector</span></div>
<div class="line">    Write32(FP_COMP0_Addr, (resetVect | FPB_ENABLE));   <span class="comment">// Set BP0 to Reset Vector (ARMv8M)</span></div>
<div class="line">    Write32(FP_CTRL_Addr,  (FPB_KEY   | FPB_ENABLE));   <span class="comment">// Enable FPB</span></div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">  </div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    Read32(DHCSR_Addr);                                 <span class="comment">// Read DHCSR to clear potentially set DHCSR.S_RESET_ST bit</span></div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><p>After reset is performed and the processor is halted (on the breakpoint enabled in <b>ResetCatchSet</b>) the <a class="el" href="debug_description.html#resetCatchClear">ResetCatchClear</a> sequence is executed. There in addition to the default functionality we need to clear the breakpoint introduced in the customized <b>ResetCatchSet</b> sequence.</p>
<p><a class="anchor" id="example1_resetCatchClear"></a><b>Example 1: ResetCatchClear </b></p>
<p>Below is a <b>ResetCatchClear</b> function for an Armv8-M core that corresponds to the <b>ResetCatchSet</b> sequence shown in <a class="el" href="dbg_debug_sqns.html#example1_resetCatchSet">Example 1: ResetCatchSet</a>:</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetCatchClear&quot;</span>&gt;</div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    __var DEMCR_Addr    = 0xE000EDFC;</div>
<div class="line">    __var FP_CTRL_Addr  = 0xE0002000;</div>
<div class="line">    __var FP_COMP0_Addr = 0xE0002008;</div>
<div class="line">    __var FPB_KEY       = 0x00000002;</div>
<div class="line">    __var value         = 0;</div>
<div class="line">  </div>
<div class="line">    value = Read32(DEMCR_Addr);</div>
<div class="line">    Write32(DEMCR_Addr, (value &amp;amp; ~0x00000001));     <span class="comment">// Disable Reset Vector Catch in DEMCR</span></div>
<div class="line">  </div>
<div class="line">    Write32(FP_COMP0_Addr, 0x00000000);                 <span class="comment">// Clear BP0</span></div>
<div class="line">    Write32(FP_CTRL_Addr,  FPB_KEY   );                 <span class="comment">// Disable FPB</span></div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><p><a class="anchor" id="example2_resetCatchSet"></a><b>Example 2: ResetCatchSet</b></p>
<p>In some cases the <b>ResetCatchSet</b> sequence shall behave differently depending on where the obtained Reset Vector is located. Such differentiation can be introduced using XML <b>&lt;control&gt;</b> element. For example Cortex-M0/M0+/M1/M3/M4 cores have a FBP/BPU limitations that doesn't allow to set an FPB breakpoint for code memory above 0x20000000. For systems that have firmware located above this address (mostly in large external flash) the debugger can just rely on the Reset Vector Catch to stop right after reset and can't jump to the reset vector. Here is corresponding debug sequence:</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetCatchSet&quot;</span>&gt;</div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    __var DHCSR_Addr = 0xE000EDF0;</div>
<div class="line">    __var DEMCR_Addr = 0xE000EDFC;</div>
<div class="line">    __var FPB_BKPT_H = 0x80000000;</div>
<div class="line">    __var FPB_BKPT_L = 0x40000000;</div>
<div class="line">    __var FPB_COMP_M = 0x1FFFFFFC;</div>
<div class="line">    __var FPB_KEY    = 0x00000002;</div>
<div class="line">    __var FPB_ENABLE = 0x00000001;</div>
<div class="line">    __var value      = 0;</div>
<div class="line">        __var resetVect  = 0x00000000;</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Run over Bootloader</span></div>
<div class="line">    value = Read32(DEMCR_Addr);</div>
<div class="line">    Write32(DEMCR_Addr, (value &amp;amp; ~0x00000001));    <span class="comment">// Disable Reset Vector Catch</span></div>
<div class="line">        </div>
<div class="line">    Write32(0x40000000, 0x00000002);    <span class="comment">// Map Flash to Vectors</span></div>
<div class="line">    resetVect = Read32 (0x00000004);        <span class="comment">// Read Reset Vector</span></div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">  </div>
<div class="line">  &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;resetVect &amp;lt; 0x20000000&quot;</span> info=<span class="stringliteral">&quot;Set and enable breakpoint&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">          <span class="comment">//determine if instruction is at upper or lower half-word in an aligned 4-byte block</span></div>
<div class="line">      value = ((resetVect &amp;amp; 0x02) ? FPB_BKPT_H : FPB_BKPT_L) | (resetVect &amp;amp; FPB_COMP_M) | FPB_ENABLE ;</div>
<div class="line">      Write32(0xE0002008, value);       <span class="comment">// Set BP0 to Reset Vector</span></div>
<div class="line">      value = FPB_KEY | FPB_ENABLE;</div>
<div class="line">      Write32(0xe0002000, value);       <span class="comment">// Enable FPB</span></div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/control&gt;</div>
<div class="line">  </div>
<div class="line">  &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;resetVect &amp;gt;= 0x20000000&quot;</span> info=<span class="stringliteral">&quot;Enable reset vector catch&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      <span class="comment">// Enable Reset Vector Catch in DEMCR</span></div>
<div class="line">      value = Read32(DEMCR_Addr);</div>
<div class="line">      Write32(DEMCR_Addr, (value | 0x00000001));</div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/control&gt;</div>
<div class="line">  </div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    Read32(DHCSR_Addr);                   <span class="comment">// Read DHCSR to clear potentially set DHCSR.S_RESET_ST bit</span></div>
<div class="line">  &lt;/block&gt;</div>
<div class="line">  </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><p><b>Example 2: ResetCatchClear</b></p>
<p>The <b>ResetCatchClear</b> sequence from <a class="el" href="dbg_debug_sqns.html#example1_resetCatchClear">Example 1</a> can also be used with the <a class="el" href="dbg_debug_sqns.html#example2_resetCatchSet">Example 2: ResetCatchSet</a> as there's no special handling additionally required.</p>
<p><b>Other modifications</b></p>
<p>Additionally the reset behavior can be made configurable per project via custom global debug access variables and a *.dbgconf file. See <a class="el" href="dbg_debug_sqns.html#dbg_sqns_dbgconf">Enable device-specific debug configurations</a> for additional details.</p>
<p>In some cases also the reset sequences (<b>ResetSystem</b>, <b>ResetProcessor</b>, <b>ResetHardware</b>) need to be adjusted to ensure proper bootloader handling. For example for debug authentication or bootloader configuration purposes. The actual implementation is very device and use case specific.</p>
<h1><a class="anchor" id="dbg_sqns_multicore"></a>
Handle debug in multi-core systems</h1>
<p>To correctly debug multicore systems, first of all the debug connection shall be correctly specified using <a class="el" href="pdsc_family_pg.html#element_debug">debug</a>. See <a class="el" href="dbg_setup_access.html#dbg_debug">Specify CPU debug connection</a> for description and examples.</p>
<p>To achieve correct debug operation on a multi-core system often modification of the predefined debug sequences are required. The actual implementation very much depends on the particular system architecture.</p>
<p>The <a class="el" href="debug_description.html#usage_of_sequences">Usage of debug access sequences</a> provides example flows for debugger operation. These flows shall be analyzed for particular system and different implementations may be required for each available core.</p>
<p>Recommendations described in previous sections such as <a class="el" href="dbg_debug_sqns.html#dbg_sqns_errors">error-handling</a>, <a class="el" href="dbg_debug_sqns.html#dbg_sqns_trace">trace configuration</a>, <a class="el" href="dbg_debug_sqns.html#dbg_sqns_boot">bootloader support</a> can be applied for individual cores in the multi-core system as well. Using the <b>Pname</b> identifier in the <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> element it is possible to specify the debug access sequence for a particular core.</p>
<p>The most multi-core Cortex-M systems have their CPUs intended for running different applications and not for load balancing. For simplicity we consider further such an assymmetric (AMP) dual-core system. In this system the CPUs can have either equal roles or master-slave dependancy. The roles can also be either predefined or configurable.</p>
<p>Sections below explain additional use-cases specific for multi-core systems:</p>
<ul>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_multicore_reset">Reset sequences</a></li>
<li><a class="el" href="dbg_debug_sqns.html#dbg_sqns_multicore_debug">Debug sequences for different use cases</a></li>
</ul>
<h2><a class="anchor" id="dbg_sqns_multicore_reset"></a>
Reset sequences</h2>
<p>Multi-core devices often have quite unique reset systems that a debugger shall use correctly when connecting to a target and during debug operation. For that the default reset debug sequences (see <a class="el" href="dbg_debug_sqns.html#dbg_sqns_reset">Implement reset for debug access</a>) need to be overwritten or require processor-specific implementations. Below is an overview for different reset types:</p>
<ul>
<li><a class="el" href="debug_description.html#resetHardware">ResetHardware</a> is a hardware-triggered system-wide reset and should not be differentiated per individual core. However its default implementation may need to be overwritten in order to take the system configuration into account (master-slave, etc.).</li>
<li><a class="el" href="debug_description.html#resetSystem">ResetSystem</a> is a software-triggered system-wide reset. It is assumed to be applied to the whole system and shouldn't be core-specific. But same as with <b>ResetHardware</b> it may require different implementation, for example to ensure correct reset in master-slave systems.</li>
<li><a class="el" href="debug_description.html#resetProcessor">ResetProcessor</a> is a software-triggered local reset for the specified CPU (or if required CPU subsystem). It needs to be differentiated for each core and is done by overwriting predefined <b>ResetProcessor</b> sequence for each CPU. Custom debug access sequences can be used to simplify code structure as shown in the example below:</li>
</ul>
<div class="fragment"><div class="line">&lt;sequences&gt;</div>
<div class="line"><span class="comment">//-- Begin: ResetProcessor Sequence for Cortex-M4</span></div>
<div class="line">  &lt;sequence name=<span class="stringliteral">&quot;ResetProcessor&quot;</span> Pname=<span class="stringliteral">&quot;CM4&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      Sequence(<span class="stringliteral">&quot;ResetProcessor_CM4&quot;</span>);</div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/sequence&gt;</div>
<div class="line"></div>
<div class="line"><span class="comment">//-- Begin: ResetProcessor Sequence for Cortex-M0</span></div>
<div class="line">  &lt;sequence name=<span class="stringliteral">&quot;ResetProcessor&quot;</span> Pname=<span class="stringliteral">&quot;CM0plus&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      Sequence(<span class="stringliteral">&quot;ResetProcessor_CM0plus&quot;</span>);</div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/sequence&gt;</div>
<div class="line">  ...</div>
<div class="line">&lt;/sequences&gt;</div>
</div><!-- fragment --><p>In the example above the reset functionality itself is implemented in the user-defined (custom) debug sequences <code>ResetProcessor_CM0plus</code> and <code>ResetProcessor_CM4</code>.</p>
<p>The same <b>Pname</b> identifier shall be used in <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> element as defined in the corresponding <a class="el" href="pdsc_family_pg.html#element_processor">processor</a> element ('CM0plus' or 'CM4' in this example).</p>
<p>Following the same concept the <a class="el" href="debug_description.html#resetCatchSet">ResetCatchSet</a> and <a class="el" href="debug_description.html#resetCatchClear">ResetCatchClear</a> sequences may need to be overwritten for individual cores, as reset vectors for different cores are located in different areas and hence the breakpoint for halt after reset shall be set differently. The approach is very similar to the one described in <a class="el" href="dbg_debug_sqns.html#dbg_sqns_boot">Support bootloader operation</a>.</p>
<h2><a class="anchor" id="dbg_sqns_multicore_debug"></a>
Debug sequences for different use cases</h2>
<p>When debugging an application running on a processor in a multi-core system, it is often required to have special control over the processors in the system. For example in a master-slave system it may be desired to debug only the application on the slave. For that debugger needs to ensure that the slave is running independent from the master. Debug-related sequence <a class="el" href="debug_description.html#debugCoreStart">DebugCoreStart</a> can be used for that. Below is an example for NXP LPC4300 family, with <b>ReleaseM0OnConnect</b> is a configuration parameter specified via *.dbgconf as explained in <a class="el" href="dbg_debug_sqns.html#dbg_sqns_dbgconf">Enable device-specific debug configurations</a>. </p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;DebugCoreStart&quot;</span> Pname=<span class="stringliteral">&quot;Cortex-M0&quot;</span>&gt;</div>
<div class="line">  &lt;block&gt;</div>
<div class="line">    <span class="comment">// Default implementation</span></div>
<div class="line">    <span class="comment">// Enable Core Debug via DHCSR</span></div>
<div class="line">    Write32(0xE000EDF0, 0xA05F0001);</div>
<div class="line">  &lt;/block&gt;</div>
<div class="line"></div>
<div class="line">  &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;ReleaseM0OnConnect&quot;</span>&gt;</div>
<div class="line">    &lt;block&gt;</div>
<div class="line">      <span class="comment">// Release M0 from reset</span></div>
<div class="line">      Write32(0x40053104, 0x00000000);  <span class="comment">// RESET_CTRL1: Clear M0APP_RST (Bit 24)</span></div>
<div class="line">    &lt;/block&gt;</div>
<div class="line">  &lt;/control&gt;</div>
<div class="line">&lt;/sequence&gt; </div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="coresight_setup.html">Debug Setup with CMSIS-Pack</a></li><li class="navelem"><a class="el" href="dbg_setup_tutorial.html">Debug Setup Tutorial</a></li>
    <li class="footer">Generated on Thu Apr 9 2020 16:06:03 for CMSIS-Pack Version 1.6.3 by Arm Ltd. All rights reserved.
	<!--
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6 
	-->
	</li>
  </ul>
</div>
</body>
</html>
